Developer CD Series 1998 April: Mac OS SDK

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / AIncludes / DriverGestalt.a < prev next >

Wrap

Text File | 1998-02-12 | 19.5 KB | 413 lines | [TEXT/MPS ]

; ; File: DriverGestalt.a ; ; Contains: Driver Gestalt interfaces ; ; Version: Technology: System 7.5 ; Release: Universal Interfaces 3.1 ; ; Copyright: © 1995-1998 by Apple Computer, Inc., all rights reserved ; ; Bugs?: Please include the the file and version information (from above) with ; the problem description. Developers belonging to one of the Apple ; developer programs can submit bug reports to: ; ; devsupport@apple.com ; ; IF &TYPE('__DRIVERGESTALT__') = 'UNDEFINED' THEN __DRIVERGESTALT__ SET 1 IF &TYPE('__MACTYPES__') = 'UNDEFINED' THEN include 'MacTypes.a' ENDIF IF &TYPE('__OSUTILS__') = 'UNDEFINED' THEN include 'OSUtils.a' ENDIF IF &TYPE('__SCSI__') = 'UNDEFINED' THEN include 'SCSI.a' ENDIF ; __________________________________________________________________________________ ; The Driver Gestalt bit in the dCtlFlags kbDriverGestaltEnable EQU 2 kmDriverGestaltEnableMask EQU $04 ; __________________________________________________________________________________ ; Driver Gestalt related csCodes kDriverGestaltCode EQU 43 ; various uses kDriverConfigureCode EQU 43 ; various uses kdgLowPowerMode EQU 70 ; Sets/Returns the current energy consumption level kdgReturnDeviceID EQU 120 ; returns SCSI DevID in csParam[0] kdgGetCDDeviceInfo EQU 121 ; returns CDDeviceCharacteristics in csParam[0] ; __________________________________________________________________________________ ; Driver Gestalt selectors kdgVersion EQU 'vers' ; Version number of the driver in standard Apple format kdgDeviceType EQU 'devt' ; The type of device the driver is driving. kdgInterface EQU 'intf' ; The underlying interface that the driver is using (if any) kdgSync EQU 'sync' ; True if driver only behaves synchronously. kdgBoot EQU 'boot' ; value to place in PRAM for this drive (long) kdgWide EQU 'wide' ; True if driver supports ioWPosOffset kdgPurge EQU 'purg' ; Driver purge permission (True = purge; False = no purge) kdgSupportsSwitching EQU 'lpwr' ; True if driver supports power switching kdgMin3VPower EQU 'pmn3' ; Minimum 3.3V power consumption in microWatts kdgMin5VPower EQU 'pmn5' ; Minimum 5V power consumption in microWatts kdgMax3VPower EQU 'pmx3' ; Maximum 3.3V power consumption in microWatts kdgMax5VPower EQU 'pmx5' ; Maximum 5V power consumption in microWatts kdgInHighPower EQU 'psta' ; True if device is currently in high power mode kdgSupportsPowerCtl EQU 'psup' ; True if driver supports following five calls kdgAPI EQU 'dAPI' ; API support for PC Exchange kdgEject EQU 'ejec' ; Eject options for shutdown/restart (Shutdown Mgr) kdgFlush EQU 'flus' ; Determine if disk driver supports flush and if it needs a flush kdgVMOptions EQU 'vmop' ; Disk drive's Virtual Memory options kdgMediaInfo EQU 'minf' ; return media specific information ; __________________________________________________________________________________ ; Driver Configure selectors kdcFlush EQU 'flus' ; Tell a disk driver to flush its cache and any hardware caches kdcVMOptions EQU 'vmop' ; Change the disk driver's Virtual Memory options ; __________________________________________________________________________________ ; control parameter block for Driver Configure calls DriverConfigParam RECORD 0 qLink ds.l 1 ; offset: $0 (0) qType ds.w 1 ; offset: $4 (4) ioTrap ds.w 1 ; offset: $6 (6) ioCmdAddr ds.l 1 ; offset: $8 (8) ioCompletion ds.l 1 ; offset: $C (12) ioResult ds.w 1 ; offset: $10 (16) ioNamePtr ds.l 1 ; offset: $12 (18) ioVRefNum ds.w 1 ; offset: $16 (22) ioCRefNum ds.w 1 ; offset: $18 (24) ; refNum for I/O operation csCode ds.w 1 ; offset: $1A (26) ; == kDriverConfigureCode driverConfigureSelector ds.l 1 ; offset: $1C (28) driverConfigureParameter ds.l 1 ; offset: $20 (32) sizeof EQU * ; size: $24 (36) ENDR ; __________________________________________________________________________________ ; status parameter block for Driver Gestalt calls DriverGestaltParam RECORD 0 qLink ds.l 1 ; offset: $0 (0) qType ds.w 1 ; offset: $4 (4) ioTrap ds.w 1 ; offset: $6 (6) ioCmdAddr ds.l 1 ; offset: $8 (8) ioCompletion ds.l 1 ; offset: $C (12) ioResult ds.w 1 ; offset: $10 (16) ioNamePtr ds.l 1 ; offset: $12 (18) ioVRefNum ds.w 1 ; offset: $16 (22) ioCRefNum ds.w 1 ; offset: $18 (24) ; refNum for I/O operation csCode ds.w 1 ; offset: $1A (26) ; == kDriverGestaltCode driverGestaltSelector ds.l 1 ; offset: $1C (28) ; 'sync', 'vers', etc. driverGestaltResponse ds.l 1 ; offset: $20 (32) ; Could be a pointer, bit field or other format driverGestaltResponse1 ds.l 1 ; offset: $24 (36) ; Could be a pointer, bit field or other format driverGestaltResponse2 ds.l 1 ; offset: $28 (40) ; Could be a pointer, bit field or other format driverGestaltResponse3 ds.l 1 ; offset: $2C (44) ; Could be a pointer, bit field or other format driverGestaltfiller ds.w 1 ; offset: $30 (48) ; To pad out to the size of a controlPB sizeof EQU * ; size: $32 (50) ENDR ; Note that the various response definitions are overlays of the response fields above. ; For instance the deviceType response would be returned in driverGestaltResponse. ; The DriverGestaltPurgeResponse would be in driverGestaltResponse and driverGestaltResponse1 ; ; __________________________________________________________________________________ ; Device Types response DriverGestaltDevTResponse RECORD 0 deviceType ds.l 1 ; offset: $0 (0) sizeof EQU * ; size: $4 (4) ENDR kdgDiskType EQU 'disk' ; standard r/w disk drive kdgTapeType EQU 'tape' ; tape drive kdgPrinterType EQU 'prnt' ; printer kdgProcessorType EQU 'proc' ; processor kdgWormType EQU 'worm' ; write-once kdgCDType EQU 'cdrm' ; cd-rom drive kdgFloppyType EQU 'flop' ; floppy disk drive kdgScannerType EQU 'scan' ; scanner kdgFileType EQU 'file' ; Logical Partition type based on a file (Drive Container) kdgRemovableType EQU 'rdsk' ; A removable media hard disk drive ie. Syquest, Bernioulli ; __________________________________________________________________________________ ; Device Interfaces response DriverGestaltIntfResponse RECORD 0 interfaceType ds.l 1 ; offset: $0 (0) sizeof EQU * ; size: $4 (4) ENDR kdgScsiIntf EQU 'scsi' kdgPcmciaIntf EQU 'pcmc' kdgATAIntf EQU 'ata ' kdgFireWireIntf EQU 'fire' kdgExtBus EQU 'card' ; __________________________________________________________________________________ ; Power Saving DriverGestaltPowerResponse RECORD 0 powerValue ds.l 1 ; offset: $0 (0) ; Power consumed in µWatts sizeof EQU * ; size: $4 (4) ENDR ; __________________________________________________________________________________ ; Disk Specific DriverGestaltSyncResponse RECORD 0 behavesSynchronously ds.b 1 ; offset: $0 (0) pad ds.b 3 ; offset: $1 (1) sizeof EQU * ; size: $4 (4) ENDR DriverGestaltBootResponse RECORD 0 extDev ds.b 1 ; offset: $0 (0) ; Packed target (upper 5 bits) LUN (lower 3 bits) partition ds.b 1 ; offset: $1 (1) ; Unused SIMSlot ds.b 1 ; offset: $2 (2) ; Slot SIMsRSRC ds.b 1 ; offset: $3 (3) ; sRsrcID sizeof EQU * ; size: $4 (4) ENDR DriverGestaltAPIResponse RECORD 0 partitionCmds ds.w 1 ; offset: $0 (0) ; if bit 0 is nonzero, supports partition control and status calls ; prohibitMounting (control, kProhibitMounting) ; partitionToVRef (status, kGetPartitionStatus) ; getPartitionInfo (status, kGetPartInfo) unused1 ds.w 1 ; offset: $2 (2) ; all the unused fields should be zero unused2 ds.w 1 ; offset: $4 (4) unused3 ds.w 1 ; offset: $6 (6) unused4 ds.w 1 ; offset: $8 (8) unused5 ds.w 1 ; offset: $A (10) unused6 ds.w 1 ; offset: $C (12) unused7 ds.w 1 ; offset: $E (14) unused8 ds.w 1 ; offset: $10 (16) unused9 ds.w 1 ; offset: $12 (18) unused10 ds.w 1 ; offset: $14 (20) sizeof EQU * ; size: $16 (22) ENDR DriverGestaltFlushResponse RECORD 0 canFlush ds.b 1 ; offset: $0 (0) ; Return true if driver supports the ; kdcFlush Driver Configure _Control call needsFlush ds.b 1 ; offset: $1 (1) ; Return true if driver/device has data cached ; and needs to be flushed when the disk volume ; is flushed by the File Manager pad ds.b 2 ; offset: $2 (2) sizeof EQU * ; size: $4 (4) ENDR ; Flags for purge permissions kbCloseOk EQU 0 ; Ok to call Close kbRemoveOk EQU 1 ; Ok to call RemoveDrvr kbPurgeOk EQU 2 ; Ok to call DisposePtr kmNoCloseNoPurge EQU 0 kmOkCloseNoPurge EQU $03 kmOkCloseOkPurge EQU $07 ; Driver purge permission structure DriverGestaltPurgeResponse RECORD 0 purgePermission ds.w 1 ; offset: $0 (0) ; 0 = Do not change the state of the driver ; 3 = Do Close() and DrvrRemove() this driver ; but don't deallocate driver code ; 7 = Do Close(), DrvrRemove(), and DisposePtr() purgeReserved ds.w 1 ; offset: $2 (2) purgeDriverPointer ds.l 1 ; offset: $4 (4) ; pointer to the start of the driver block (valid ; only of DisposePtr permission is given sizeof EQU * ; size: $8 (8) ENDR DriverGestaltEjectResponse RECORD 0 ejectFeatures ds.l 1 ; offset: $0 (0) ; sizeof EQU * ; size: $4 (4) ENDR ; Flags for Ejection Features field kRestartDontEject EQU 0 ; Dont Want eject during Restart kShutDownDontEject EQU 1 ; Dont Want eject during Shutdown kRestartDontEject_Mask EQU $01 kShutDownDontEject_Mask EQU $02 ; ; The DriverGestaltVMOptionsResponse is returned by a disk driver in response to a ; kdgVMOptions Driver Gestalt request. This allows a disk driver to tell VM a few ; things about a disk drive. For example: ; ; • A drive that should never be in the page fault path should return kAllowVMNoneMask. ; Examples of this are drives that have manual eject buttons that are not disabled by ; software, drives with very slow throughput, or drives that depend on ; a network connection. ; • A drive that should never be written to but is safe for read-only file mapping ; should return kAllowVMReadOnlyMask. Examples of this are WORM drives where each write ; eats write-once space on the disk and CD-ROM drives which are read-only media. ; • A drive that should allow VM to create its main backing store file should return ; kAllowVMReadWriteMask. Examples of this are fast read/write drives that don't allow ; manual eject and don't use a network connection. ; ; A disk driver must look at the ioVRefNum field of the DriverGestaltParam to determine ; what disk drive this call is for. This is a per-drive call, not a per-driver call. ; ; The only three valid responses to kdgVMOptions at this time are kAllowVMNoneMask, ; kAllowVMReadOnlyMask, and kAllowVMReadWriteMask (i.e., setting only kAllowVMWriteBit ; is not valid). ; ; Important: All bits not defined here are reserved and should be set to zero until ; they are defined for a specific purpose. ; ; The kdcVMOptions Driver Configure _Control call provides the ability to change a driver's ; response to kdgVMOptions Driver Gestalt requests. A driver should return controlErr if ; it doesn't want to provide the ability to change the kdgVMOptions response. If a driver ; supports the kdcVMOptions Driver Configure _Control call, but is asked to set an option bit ; that it doesn't support (for example, if a read-only device is asked to set the kAllowVMWriteBit), ; it should return paramErr. ; DriverGestaltVMOptionsResponse RECORD 0 vmOptions ds.l 1 ; offset: $0 (0) sizeof EQU * ; size: $4 (4) ENDR ; Bits and masks for DriverGestaltVMOptionsResponse.vmOptions field kAllowVMReadBit EQU 0 ; Allow VM to use this drive for read access kAllowVMWriteBit EQU 1 ; Allow VM to use this drive for write access kAllowVMNoneMask EQU 0 kAllowVMReadOnlyMask EQU $01 kAllowVMReadWriteMask EQU $03 ; ; The DriverGestaltMediaInfoResponse is returned by a disk driver in response to a ; kdgMediaInfo DriverGestalt request. This allows a disk driver to tell callers the ; physical block size, the number of blocks that are of that size, and the media type ; for a given device. ; ; A disk driver must look at the ioVRefNum field of the DriverGestaltParam to determine ; what disk drive this call is for. This is a per-drive call, not a per-driver call. ; ; On drives that support ejectable media, the response can change depending on what ; media is currently in the drive. ; DriverGestaltMediaInfoResponse RECORD 0 numberBlocks ds.l 1 ; offset: $0 (0) ; number of blocks blockSize ds.l 1 ; offset: $4 (4) ; physical size of blocks mediaType ds.w 1 ; offset: $8 (8) ; media type identifier sizeof EQU * ; size: $A (10) ENDR ; DriverGestaltMediaInfoResponse.mediaType constants kMediaTypeUnknown EQU 128 ; media type is unknown kMediaTypeCDROM EQU 129 ; media type is a CD-ROM kMediaTypeDVDROM EQU 130 ; media type is a DVD-ROM kMediaTypeNoMedia EQU -1 ; no media is present ; __________________________________________________________________________________ ; CD-ROM Specific ; The CDDeviceCharacteristics result is returned in csParam[0] and csParam[1] of a ; standard CntrlParam parameter block called with csCode kdgGetCDDeviceInfo. ; CDDeviceCharacteristics RECORD 0 speedMajor ds.b 1 ; offset: $0 (0) ; High byte of fixed point number containing drive speed speedMinor ds.b 1 ; offset: $1 (1) ; Low byte of "" CD 300 == 2.2, CD_SC == 1.0 etc. cdFeatures ds.w 1 ; offset: $2 (2) ; Flags field for features and transport type of this CD-ROM sizeof EQU * ; size: $4 (4) ENDR cdFeatureFlagsMask EQU $FFFC ; The Flags are in the first 14 bits of the cdFeatures field cdTransportMask EQU $0003 ; The transport type is in the last 2 bits of the cdFeatures field ; Flags for CD Features field cdMute EQU 0 ; The following flags have the same bit number cdLeftToChannel EQU 1 ; as the Audio Mode they represent. Don't change cdRightToChannel EQU 2 ; them without changing dControl.c cdLeftPlusRight EQU 3 ; Reserve some space for new audio mixing features (4-7) cdSCSI_2 EQU 8 ; Supports SCSI2 CD Command Set cdStereoVolume EQU 9 ; Can support two different volumes (1 on each channel) cdDisconnect EQU 10 ; Drive supports disconnect/reconnect cdWriteOnce EQU 11 ; Drive is a write/once (CD-R?) type drive cdMute_Mask EQU $01 cdLeftToChannel_Mask EQU $02 cdRightToChannel_Mask EQU $04 cdLeftPlusRight_Mask EQU $08 cdSCSI_2_Mask EQU $0100 cdStereoVolume_Mask EQU $0200 cdDisconnect_Mask EQU $0400 cdWriteOnce_Mask EQU $0800 ; Transport types cdCaddy EQU 0 ; CD_SC,CD_SC_PLUS,CD-300 etc. cdTray EQU 1 ; CD_300_PLUS etc. cdLid EQU 2 ; Power CD - eg no eject mechanism ; the following are used by PC Exchange (and Apple DOS/PC Compatibility Card) ; Control Codes kRegisterPartition EQU 50 ; PCX needs a new Drive (for a non-macintosh partition found on the disk) OLD_REGISTER_PARTITION EQU 301 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card THE_DRIVE EQU 0 ; DrvQElPtr for the partition to register THE_PHYS_START EQU 1 ; The start of the partition in logical blocks THE_PHYS_SIZE EQU 2 ; The size of the partition in logical blocks kGetADrive EQU 51 ; control call to ask the driver to create a drive OLD_GET_A_DRIVE EQU 302 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card THE_VAR_QUEL EQU 0 ; a VAR parameter for the returned DrvQElPtr kProhibitMounting EQU 52 ; Dont allow mounting of the following drives kOldProhibitMounting EQU 2100 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card kProhibitDevice EQU 0 ; CS Param 0 and 1 (partInfoRecPtr) kIsContainerMounted EQU 53 kOldIsContainerMounted EQU 2201 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card kContainerVRef EQU 0 ; CS Param 0 and 1 (VRefNum) kContainerParID EQU 1 ; CS Param 2 and 3 (Parent ID) kContainerName EQU 2 ; CS Param 4 and 5 (File Name) kContainerResponse EQU 3 ; CS Param 6 and 7 (VAR pointer to short result) kMountVolumeImg EQU 54 OLD_MOUNT_VOLUME_IMG EQU 2000 MV_HOST_VREFNUM EQU 0 MV_HOST_PAR_ID EQU 1 MV_HOST_NAME EQU 2 MV_REQ_PERM EQU 3 ; Status Codes kGetPartitionStatus EQU 50 ; what is the status of this partition? kOldGetPartitionStatus EQU 2200 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card kDeviceToQuery EQU 0 ; CS Param 0 and 1 (partInfoRecPtr) kDeviceResponse EQU 1 ; CS Param 2 and 3 (VAR pointer to short result) kGetPartInfo EQU 51 ; Get a partition info record based on the provided vrefnum kOldGetPartInfo EQU 2300 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card kPartInfoResponse EQU 0 ; var parameter (pointer to partInfoRec) CSParam [0-1] kGetContainerAlias EQU 52 ; Get the alias that describes the file this drive was mounted from. kOldGetContainerAlias EQU 2400 ; left in for compatibility with shipping Apple DOS/PC Compatibility Card kGetAliasResponse EQU 0 ; var parameter (pointer to a Handle) CSParam [0-1] ; the result codes to come from the driver interface DRIVER_NOT_INSTALLED EQU -1 DRIVER_BUSY EQU -2 CANT_MOUNT_WITHIN_THIS_FS EQU -3 ; can only mount container within residing on HFS volume VOLUME_ALREADY_MOUNTED EQU -4 ; Already Mounted ; requisite structures for PCX control and status calls kMaxProhibted EQU 2 ; the max number of volumes the PC can possibly have mounted ; GestaltSelector for Finding Driver information kGetDriverInfo EQU 'vdrc' VerifyCmd EQU 5 FormatCmd EQU 6 EjectCmd EQU 7 ; Partition information passed back and forth between PCX and the driver partInfoRec RECORD 0 SCSIID ds DeviceIdent ; offset: $0 (0) ; DeviceIdent for the device physPartitionLoc ds.l 1 ; offset: $4 (4) ; physical block number of beginning of partition partitionNumber ds.l 1 ; offset: $8 (8) ; the partition number of this partition sizeof EQU * ; size: $C (12) ENDR ; typedef struct partInfoRec * partInfoRecPtr vPartInfoRec RECORD 0 VPRTVers ds.b 1 ; offset: $0 (0) ; Virtual partition version number VPRTType ds.b 1 ; offset: $1 (1) ; virtual partition type (DOS, HFS, etc) drvrRefNum ds.w 1 ; offset: $2 (2) ; Driver Reference number of partition driver sizeof EQU * ; size: $4 (4) ENDR ; typedef struct vPartInfoRec * vPartInfoRecPtr ; Information related to DOS partitions kDOSSigLow EQU $01FE ; offset into boot block for DOS signature kDOSSigHi EQU $01FF ; offset into boot block for DOS signature kDOSSigValLo EQU $55 ; DOS signature value in low byte kDOSSigValHi EQU $AA ; DOS signature value in high byte ENDIF ; __DRIVERGESTALT__